package com.jfire.orm.function;

import java.sql.Connection;
import java.util.List;

/**
 * 代表一个connection链接，提供各种dao操作入口
 * 
 * @author eric
 *         
 */
public interface SqlSession extends AutoCloseable
{
    /**
     * 将一个对象保存或者更新到数据库。如果对象的id属性有值，就是更新操作，如果没有值就是插入操作
     * 
     * @param <T>
     *            
     * @param entity
     * @return
     */
    public <T> void save(T entity);
    
    /**
     * 将一个对象以插入的形式保存到数据库
     * 
     * @param entity
     */
    public void insert(Object entity);
    
    /**
     * 删除对象所对应的表的一条记录
     * 
     * @param entityClass 代表数据库表的类对象
     * @param pk 主键
     * @return
     */
    public boolean delete(Object entity);
    
    /**
     * 根据主键获取一条记录，并且使用该记录创造一个对象
     * 
     * @param entityClass 代表数据库表的类对象
     * @param pk 主键
     * @return 代表该行记录的对象实例
     */
    public <T> T get(Class<T> entityClass, Object pk);
    
    /**
     * 根据给定的接口，返回符合sqlorm规范的接口实现
     * 
     * @param entityClass
     * @return
     */
    public <T> T getMapper(Class<T> entityClass);
    
    /**
     * 关闭session，释放数据库链接
     */
    public void close();
    
    /**
     * 启动事务,将该数据库链接设置为非自动提交模式
     */
    public void beginTransAction();
    
    /**
     * 依据事务传播策略进行事务提交请求操作（在单一事务传播情况下，内嵌事务的提交只会消耗提交数，不会真的执行提交操作）
     */
    public void commit();
    
    /**
     * 提交事务到数据库，但不改变当前数据库链接的提交模式
     */
    public void flush();
    
    /**
     * 事务回滚
     */
    public void rollback();
    
    /**
     * 获取当前session使用的数据库链接
     * 
     * @return
     */
    public Connection getConnection();
    
    /**
     * 使用sql语句进行查询，返回的数据内容的类型格式和resultTypes一致。每一行数据组装成一个Object[]放入list中
     * 
     * @param resultType
     * @param sql
     * @param params
     * @return
     */
    public List<Object[]> listQuery(Class<?>[] resultTypes, String sql, Object... params);
    
    /**
     * 使用sql语句进行查询，返回的内容是多行，使用自定义对象进行映射组装
     * 
     * @param resultTypes
     * @param sql
     * @param params
     * @return
     */
    public <T> List<T> listQuery(Class<T> resultTypes, String sql, Object... params);
    
    /**
     * 使用sql语句进行查询，返回的内容是多行单列，数据内容的类型是基本类型
     * 
     * @param resultTypes
     * @param sql
     * @param params
     * @return
     */
    public <T> List<T> baseListQuery(Class<T> resultType, String sql, Object... params);
    
    /**
     * 使用sql语句进行查询，要求返回的只能是单行单列，type类型为基本类型或者基本类型的包装类
     * 
     * @param resultType
     * @param sql
     * @param params
     * @return
     */
    public <T> T baseQuery(Class<T> resultType, String sql, Object... params);
    
    /**
     * 使用sql语句进行查询，要求返回的只能单行，type类型为自定义的对象类型，将数据映射到对象的属性之中
     * 
     * @param resultTYpe
     * @param sql
     * @param params
     * @return
     */
    public <T> T query(Class<T> resultType, String sql, Object... params);
    
    /**
     * 根据给定的sql语句以及参数，进行更新类型的sql语句操作
     * 
     * @param sql
     * @param params 需要更新的参数，参数顺序需要与sql语句中的一致
     * @return 返回操作的数据库行数
     */
    public int update(String sql, Object... params);
    
    /**
     * 根据给定的sql，执行批量插入。一次迭代为一行更新的数据
     * 
     * @param sql 给定的格式化sql
     * @param iterator 迭代器，每一次迭代的数据为一行的数据
     */
    public int[] batchUpdate(String sql, List<Object[]> iterator);
    
}
